<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Introduction - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.auth.introduction.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.auth.introduction.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.auth.html">Zend_Auth</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.auth.html">Zend_Auth</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.auth.adapter.dbtable.html">Database Table Authentication</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.auth.introduction" class="section"><div class="info"><h1 class="title">Introduction</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Auth</span> provides an <acronym class="acronym">API</acronym> for authentication and
        includes concrete authentication adapters for common use case scenarios.
    </p>

    <p class="para">
        <span class="classname">Zend_Auth</span> is concerned only with <em class="emphasis">authentication</em>
        and not with <em class="emphasis">authorization</em>. Authentication is loosely defined as
        determining whether an entity actually is what it purports to be (i.e., identification),
        based on some set of credentials. Authorization, the process of deciding whether to allow
        an entity access to, or to perform operations upon, other entities is outside the scope of
        <span class="classname">Zend_Auth</span>. For more information about authorization and access
        control with Zend Framework, please see <a href="zend.acl.html" class="link"><span class="classname">Zend_Acl</span></a>.
    </p>

    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">
            The <span class="classname">Zend_Auth</span> class implements the Singleton pattern - only one
            instance of the class is available - through its static
             <span class="methodname">getInstance()</span> method. This means that using the
            <em class="emphasis">new</em> operator and the <em class="emphasis">clone</em> keyword will not
            work with the <span class="classname">Zend_Auth</span> class; use
             <span class="methodname">Zend_Auth::getInstance()</span> instead.
        </p>
    </p></blockquote>

    <div class="section" id="zend.auth.introduction.adapters"><div class="info"><h1 class="title">Adapters</h1></div>
        

        <p class="para">
            A <span class="classname">Zend_Auth</span> adapter is used to authenticate against a particular
            type of authentication service, such as <acronym class="acronym">LDAP</acronym>,
            <acronym class="acronym">RDBMS</acronym>, or file-based storage. Different adapters are likely to have
            vastly different options and behaviors, but some basic things are common among
            authentication adapters. For example, accepting authentication credentials (including a
            purported identity), performing queries against the authentication service, and
            returning results are common to <span class="classname">Zend_Auth</span> adapters.
        </p>

        <p class="para">
            Each <span class="classname">Zend_Auth</span> adapter class implements
            <span class="classname">Zend_Auth_Adapter_Interface</span>. This interface defines one method,
             <span class="methodname">authenticate()</span>, that an adapter class must implement for
            performing an authentication query. Each adapter class must be prepared prior to
            calling  <span class="methodname">authenticate()</span>. Such adapter preparation includes
            setting up credentials (e.g., username and password) and defining values for
            adapter-specific configuration options, such as database connection settings for a
            database table adapter.
        </p>

        <p class="para">
            The following is an example authentication adapter that requires a username and
            password to be set for authentication. Other details, such as how the authentication
            service is queried, have been omitted for brevity:
        </p>

        <pre class="programlisting brush: php">
class MyAuthAdapter implements Zend_Auth_Adapter_Interface
{
    /**
     * Sets username and password for authentication
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * Performs an authentication attempt
     *
     * @throws Zend_Auth_Adapter_Exception If authentication cannot
     *                                     be performed
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}
</pre>


        <p class="para">
            As indicated in its docblock,  <span class="methodname">authenticate()</span> must return an
            instance of <span class="classname">Zend_Auth_Result</span> (or of a class derived from
            <span class="classname">Zend_Auth_Result</span>). If for some reason performing an
            authentication query is impossible,  <span class="methodname">authenticate()</span> should
            throw an exception that derives from
            <span class="classname">Zend_Auth_Adapter_Exception</span>.
        </p>
    </div>

    <div class="section" id="zend.auth.introduction.results"><div class="info"><h1 class="title">Results</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Auth</span> adapters return an instance of
            <span class="classname">Zend_Auth_Result</span> with  <span class="methodname">authenticate()</span> in
            order to represent the results of an authentication attempt. Adapters populate the
            <span class="classname">Zend_Auth_Result</span> object upon construction, so that the following
            four methods provide a basic set of user-facing operations that are common to the
            results of <span class="classname">Zend_Auth</span> adapters:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                     <span class="methodname">isValid()</span> - returns <b><tt>TRUE</tt></b> if and
                    only if the result represents a successful authentication attempt
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getCode()</span> - returns a
                    <span class="classname">Zend_Auth_Result</span> constant identifier for determining
                    the type of authentication failure or whether success has occurred. This
                    may be used in situations where the developer wishes to distinguish among
                    several authentication result types. This allows developers to maintain
                    detailed authentication result statistics, for example. Another use of this
                    feature is to provide specific, customized messages to users for usability
                    reasons, though developers are encouraged to consider the risks of
                    providing such detailed reasons to users, instead of a general
                    authentication failure message. For more information, see the notes below.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getIdentity()</span> - returns the identity of the
                    authentication attempt
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getMessages()</span> - returns an array of messages
                    regarding a failed authentication attempt
                </p>
            </li>
        </ul>

        <p class="para">
            A developer may wish to branch based on the type of authentication result in order to
            perform more specific operations. Some operations developers might find useful are
            locking accounts after too many unsuccessful password attempts, flagging an IP address
            after too many nonexistent identities are attempted, and providing specific, customized
            authentication result messages to the user. The following result codes are available:
        </p>

        <pre class="programlisting brush: php">
Zend_Auth_Result::SUCCESS
Zend_Auth_Result::FAILURE
Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
Zend_Auth_Result::FAILURE_UNCATEGORIZED
</pre>


        <p class="para">
            The following example illustrates how a developer may branch on the result code:
        </p>

        <pre class="programlisting brush: php">
// inside of AuthController / loginAction
$result = $this-&gt;_auth-&gt;authenticate($adapter);

switch ($result-&gt;getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** do stuff for nonexistent identity **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** do stuff for invalid credential **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** do stuff for successful authentication **/
        break;

    default:
        /** do stuff for other failure **/
        break;
}
</pre>

    </div>

    <div class="section" id="zend.auth.introduction.persistence"><div class="info"><h1 class="title">Identity Persistence</h1></div>
        

        <p class="para">
            Authenticating a request that includes authentication credentials is useful per se, but
            it is also important to support maintaining the authenticated identity without having
            to present the authentication credentials with each request.
        </p>

        <p class="para">
            <acronym class="acronym">HTTP</acronym> is a stateless protocol, however, and techniques such as
            cookies and sessions have been developed in order to facilitate maintaining state
            across multiple requests in server-side web applications.
        </p>

        <div class="section" id="zend.auth.introduction.persistence.default"><div class="info"><h1 class="title">Default Persistence in the PHP Session</h1></div>
            

            <p class="para">
                 By default, <span class="classname">Zend_Auth</span> provides persistent storage of the
                 identity from a successful authentication attempt using the <acronym class="acronym">PHP</acronym>
                 session. Upon a successful authentication attempt,
                  <span class="methodname">Zend_Auth::authenticate()</span> stores the identity from the
                 authentication result into persistent storage. Unless configured otherwise,
                 <span class="classname">Zend_Auth</span> uses a storage class named
                 <span class="classname">Zend_Auth_Storage_Session</span>, which, in turn, uses
                 <a href="zend.session.html" class="link"><span class="classname">Zend_Session</span></a>. A custom
                 class may instead be used by providing an object that implements
                 <span class="classname">Zend_Auth_Storage_Interface</span> to
                  <span class="methodname">Zend_Auth::setStorage()</span>.
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    If automatic persistent storage of the identity is not appropriate for a
                    particular use case, then developers may forgot using the
                    <span class="classname">Zend_Auth</span> class altogether, instead using an adapter
                    class directly.
                </p>
            </p></blockquote>

            <div class="example" id="zend.auth.introduction.persistence.default.example"><div class="info"><p><b>Example #1 Modifying the Session Namespace</b></p></div>
                

                <div class="example-contents"><p>
                    <span class="classname">Zend_Auth_Storage_Session</span> uses a session namespace of
                    &#039;<span class="classname">Zend_Auth</span>&#039;. This namespace may be overridden by passing
                    a different value to the constructor of
                    <span class="classname">Zend_Auth_Storage_Session</span>, and this value is internally
                    passed along to the constructor of
                    <span class="classname">Zend_Session_Namespace</span>. This should occur before
                    authentication is attempted, since
                     <span class="methodname">Zend_Auth::authenticate()</span> performs the automatic
                    storage of the identity.
                </p></div>

                <pre class="programlisting brush: php">
// Save a reference to the Singleton instance of Zend_Auth
$auth = Zend_Auth::getInstance();

// Use &#039;someNamespace&#039; instead of &#039;Zend_Auth&#039;
$auth-&gt;setStorage(new Zend_Auth_Storage_Session(&#039;someNamespace&#039;));

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Authenticate, saving the result, and persisting the identity on
// success
$result = $auth-&gt;authenticate($authAdapter);
</pre>

            </div>
        </div>

        <div class="section" id="zend.auth.introduction.persistence.custom"><div class="info"><h1 class="title">Implementing Customized Storage</h1></div>
            

            <p class="para">
                Sometimes developers may need to use a different identity storage mechanism than
                that provided by <span class="classname">Zend_Auth_Storage_Session</span>. For such cases
                developers may simply implement <span class="classname">Zend_Auth_Storage_Interface</span>
                and supply an instance of the class to
                 <span class="methodname">Zend_Auth::setStorage()</span>.
            </p>

            <div class="example" id="zend.auth.introduction.persistence.custom.example"><div class="info"><p><b>Example #2 Using a Custom Storage Class</b></p></div>
                

                <div class="example-contents"><p>
                    In order to use an identity persistence storage class other than
                    <span class="classname">Zend_Auth_Storage_Session</span>, a developer implements
                    <span class="classname">Zend_Auth_Storage_Interface</span>:
                </p></div>

                <pre class="programlisting brush: php">
class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * Returns true if and only if storage is empty
     *
     * @throws Zend_Auth_Storage_Exception If it is impossible to
     *                                     determine whether storage
     *                                     is empty
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Returns the contents of storage
     *
     * Behavior is undefined when storage is empty.
     *
     * @throws Zend_Auth_Storage_Exception If reading contents from
     *                                     storage is impossible
     * @return mixed
     */
    public function read()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Writes $contents to storage
     *
     * @param  mixed $contents
     * @throws Zend_Auth_Storage_Exception If writing $contents to
     *                                     storage is impossible
     * @return void
     */
    public function write($contents)
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Clears contents from storage
     *
     * @throws Zend_Auth_Storage_Exception If clearing contents from
     *                                     storage is impossible
     * @return void
     */
    public function clear()
    {
        /**
         * @todo implementation
         */
    }
}
</pre>


                <div class="example-contents"><p>
                    In order to use this custom storage class,
                     <span class="methodname">Zend_Auth::setStorage()</span> is invoked before an
                    authentication query is attempted:
                </p></div>

                <pre class="programlisting brush: php">
// Instruct Zend_Auth to use the custom storage class
Zend_Auth::getInstance()-&gt;setStorage(new MyStorage());

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Authenticate, saving the result, and persisting the identity on
// success
$result = Zend_Auth::getInstance()-&gt;authenticate($authAdapter);
</pre>

            </div>
        </div>
    </div>

    <div class="section" id="zend.auth.introduction.using"><div class="info"><h1 class="title">Usage</h1></div>
        

        <p class="para">
            There are two provided ways to use <span class="classname">Zend_Auth</span> adapters:
        </p>

        <ol type="1">
            <li class="listitem">
                <p class="para">
                    indirectly, through  <span class="methodname">Zend_Auth::authenticate()</span>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    directly, through the adapter&#039;s  <span class="methodname">authenticate()</span> method
                </p>
            </li>
        </ol>

        <p class="para">
            The following example illustrates how to use a <span class="classname">Zend_Auth</span> adapter
            indirectly, through the use of the <span class="classname">Zend_Auth</span> class:
        </p>

        <pre class="programlisting brush: php">
// Get a reference to the singleton instance of Zend_Auth
$auth = Zend_Auth::getInstance();

// Set up the authentication adapter
$authAdapter = new MyAuthAdapter($username, $password);

// Attempt authentication, saving the result
$result = $auth-&gt;authenticate($authAdapter);

if (!$result-&gt;isValid()) {
    // Authentication failed; print the reasons why
    foreach ($result-&gt;getMessages() as $message) {
        echo &quot;$message\n&quot;;
    }
} else {
    // Authentication succeeded; the identity ($username) is stored
    // in the session
    // $result-&gt;getIdentity() === $auth-&gt;getIdentity()
    // $result-&gt;getIdentity() === $username
}
</pre>


        <p class="para">
            Once authentication has been attempted in a request, as in the above example, it is a
            simple matter to check whether a successfully authenticated identity exists:
        </p>

        <pre class="programlisting brush: php">
$auth = Zend_Auth::getInstance();
if ($auth-&gt;hasIdentity()) {
    // Identity exists; get it
    $identity = $auth-&gt;getIdentity();
}
</pre>


        <p class="para">
            To remove an identity from persistent storage, simply use the
             <span class="methodname">clearIdentity()</span> method. This typically would be used for
            implementing an application &quot;logout&quot; operation:
        </p>

        <pre class="programlisting brush: php">
Zend_Auth::getInstance()-&gt;clearIdentity();
</pre>


        <p class="para">
            When the automatic use of persistent storage is inappropriate for a particular use
            case, a developer may simply bypass the use of the <span class="classname">Zend_Auth</span>
            class, using an adapter class directly. Direct use of an adapter class involves
            configuring and preparing an adapter object and then calling its
             <span class="methodname">authenticate()</span> method. Adapter-specific details are discussed
            in the documentation for each adapter. The following example directly utilizes
            <span class="classname">MyAuthAdapter</span>:
        </p>

        <pre class="programlisting brush: php">
// Set up the authentication adapter
$authAdapter = new MyAuthAdapter($username, $password);

// Attempt authentication, saving the result
$result = $authAdapter-&gt;authenticate();

if (!$result-&gt;isValid()) {
    // Authentication failed; print the reasons why
    foreach ($result-&gt;getMessages() as $message) {
        echo &quot;$message\n&quot;;
    }
} else {
    // Authentication succeeded
    // $result-&gt;getIdentity() === $username
}
</pre>

    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.auth.html">Zend_Auth</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.auth.html">Zend_Auth</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.auth.adapter.dbtable.html">Database Table Authentication</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.auth.html">Zend_Auth</a></li>
  <li class="active"><a href="zend.auth.introduction.html">Introduction</a></li>
  <li><a href="zend.auth.adapter.dbtable.html">Database Table Authentication</a></li>
  <li><a href="zend.auth.adapter.digest.html">Digest Authentication</a></li>
  <li><a href="zend.auth.adapter.http.html">HTTP Authentication Adapter</a></li>
  <li><a href="zend.auth.adapter.ldap.html">LDAP Authentication</a></li>
  <li><a href="zend.auth.adapter.openid.html">Open ID Authentication</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>